Skip to content

add a description field for external doc links #4772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Jul 4, 2025
Merged

add a description field for external doc links #4772

merged 1 commit into from
Jul 4, 2025

Conversation

miguelgrinberg
Copy link
Contributor

@miguelgrinberg miguelgrinberg commented Jul 3, 2025 •
edited
Loading

Fixes #4225

This change adds a fourth column to table.csv where a description for an external documentation link can be given. This description is included in schema.json, and later transferred to the externalDocs object in the generated OpenAPI files.

Note that I have not added any descriptions, the 4th column in table.csv is empty for all rows in this PR.

@miguelgrinberg miguelgrinberg requested a review from a team as a code owner July 3, 2025 14:56
@miguelgrinberg miguelgrinberg force-pushed the add-ext-docs-description branch from d8d1372 to ee6c363 Compare July 3, 2025 15:03
@miguelgrinberg miguelgrinberg force-pushed the add-ext-docs-description branch from ee6c363 to 60809fc Compare July 3, 2025 15:07
@miguelgrinberg miguelgrinberg requested a review from lcawl July 3, 2025 15:11
@lcawl
Copy link
Contributor

lcawl commented Jul 3, 2025

To test this PR, I added a description to one of the rows in the table.csv:

ccr-auto-follow,https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/ccr-auto-follow.html,Auto-follow pattern documentation

Then I generated the output and verified that it appeared in our final OpenAPI document:

  "/_ccr/auto_follow/{name}": {
      "get": {
        "summary": "Get auto-follow patterns\n",
        "externalDocs": {
          "description": "Auto-follow pattern documentation",
          "url": "https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns",
          "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/ccr-get-auto-follow-pattern.html"
        }
...

And confirmed that the new link text appears in a preview of these docs:

image

lcawl
lcawl approved these changes Jul 3, 2025
View reviewed changes
Copy link
Contributor

@lcawl lcawl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per #4772 (comment) the output LGTM, thanks!

@miguelgrinberg miguelgrinberg force-pushed the add-ext-docs-description branch from 60809fc to a3ec0e9 Compare July 4, 2025 13:27
@miguelgrinberg miguelgrinberg merged commit c99d8ac into main Jul 4, 2025
10 checks passed
@miguelgrinberg miguelgrinberg deleted the add-ext-docs-description branch July 4, 2025 14:33
@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Jul 4, 2025

The backport to 8.19 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.19 8.19
# Navigate to the new working tree
cd .worktrees/backport-8.19
# Create a new branch
git switch --create backport-4772-to-8.19
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c99d8ac71e5818bc35d3a1a17755432c2958cdea
# Push it to GitHub
git push --set-upstream origin backport-4772-to-8.19
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.19

Then, create a pull request where the base branch is 8.19 and the compare/head branch is backport-4772-to-8.19.

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Jul 4, 2025

The backport to 8.18 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.18 8.18
# Navigate to the new working tree
cd .worktrees/backport-8.18
# Create a new branch
git switch --create backport-4772-to-8.18
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c99d8ac71e5818bc35d3a1a17755432c2958cdea
# Push it to GitHub
git push --set-upstream origin backport-4772-to-8.18
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.18

Then, create a pull request where the base branch is 8.18 and the compare/head branch is backport-4772-to-8.18.

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Jul 4, 2025

The backport to 9.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-4772-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c99d8ac71e5818bc35d3a1a17755432c2958cdea
# Push it to GitHub
git push --set-upstream origin backport-4772-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0

Then, create a pull request where the base branch is 9.0 and the compare/head branch is backport-4772-to-9.0.

github-actions bot pushed a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg @github-actions
add a description field for external doc links (#4772)
bb850a8 
(cherry picked from commit c99d8ac)
@github-actions github-actions bot mentioned this pull request Jul 4, 2025
Merged
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@github-actions @miguelgrinberg
add a description field for external doc links (#4772) (#4787)
301a7af 
(cherry picked from commit c99d8ac)

Co-authored-by: Miguel Grinberg <[email protected]>
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772)
80876da
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772)
60eda06
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772)
3671d0a
This was referenced Jul 4, 2025
Merged
Merged
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772) (#4788)
8251ab0
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772) (#4789)
41b362a
miguelgrinberg added a commit that referenced this pull request Jul 4, 2025
@miguelgrinberg
add a description field for external doc links (#4772) (#4790)
8ed534f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@lcawl lcawl lcawl approved these changes

Assignees
No one assigned
Labels
backport 8.18 backport 8.19 backport 9.0 backport 9.1 compiler generator:typescript specification
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Add support for OpenAPI externalDocs description
2 participants
@miguelgrinberg @lcawl